Skip to main content

The Response & Error Model

Every API call to Feed Clips returns a response with a predictable shape. Understanding that shape before you write any request-handling code will save you time and prevent subtle bugs, especially around partial failures and pagination.

v1 vs v2

v1 uses an RPC-style envelope for all responses. v2 uses RESTful conventions with HTTP status codes and structured pagination. The concepts below apply to both; version-specific differences are called out where they differ.

v1: The Success Envelope​

All v1 responses are wrapped in a top-level success envelope:

  • A successful response has success: true and a data field containing the result.
  • A failed response has success: false with a failureCode string identifying the problem and a human-readable message intended for developers, not end users. An optional errorData field may carry additional structured detail.

List endpoints in v1 (such as the clips fetch endpoint) add a second layer of wrapping. The top-level envelope can succeed even when individual items in the list fail. Each element in the data array is itself a success/failure envelope. This means, for example, that a single request can return some clips successfully alongside others that failed since a particular clip was not found. Your code must check the inner success field for every item, not just the outer one.

See the v1 ErrorResponse schema for the full field definitions.

v2: RESTful Responses and Pagination​

v2 replaces the RPC envelope with standard HTTP semantics:

  • Successful requests return 2xx status codes with the result body.
  • Failed requests return appropriate 4xx or 5xx status codes with an error body.
  • List endpoints return a PaginationV2 object alongside the result array, giving you a cursor or page token to fetch subsequent pages.

See the v2 ErrorResponseV2 schema for the full error structure.

Rights checks in v2​

When a v2 endpoint checks playback rights for a clip, it returns a per-clip reason field of type RightsReason: an enum with values such as NOT_FOUND, NO_STREAMING_RIGHTS, and OK. Your code should branch on the reason enum value, not on the human-readable detail string. The detail string is for developer diagnostics and may change between API versions.

What to do on failure​

  • Always read failureCode (v1) or the HTTP status plus the structured error body (v2) rather than parsing message or detail strings.
  • For list endpoints in v1, iterate the result array and handle each item's inner envelope independently.
  • For rights failures in v2, switch on RightsReason; treat unrecognized values as a signal to skip playback and log for investigation.
  • Transient errors (SERVICE_UNAVAILABLE, 5xx) are safe to retry with exponential backoff. Client errors (VALIDATION_ERROR, 4xx) indicate a bug in the request; do not retry without fixing the input first.